Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

Using the multiTranslation call and the translation temp-table

If you have a large number of strings that you want to translate in a single call, use the multiTranslation API call, as shown:

RUN multiTranslation IN gshTranslationManager ( INPUT plAllLanguages, INPUT-OUTPUT TABLE ttTranslate ).

The multiTranslation call takes two parameters:

INPUT plAllLanguages (LOGICAL) — TRUE if records should be returned for every language an input string has been translated into, otherwise FALSE. If TRUE, then extra records are created in the temp-table for each language available. The temp-table must, in that case, initially contain entries with a language object ID of 0. These are deleted in the temp-table that is returned, which, instead, contains a record for the translation into each language.
INPUT-OUTPUT TABLE ttTranslate — The ttTranslate temp-table is defined in the include file af/app/aftttranslate.i. This temp-table definition is used by the Localization Manager itself, and you can define a temp-table based on it as well as for calls such as multiTranslation.

These are the fields in the table:

/* *************************** Main Block *************************** */ &IF DEFINED(ttTranslate) = 0 &THEN DEFINE TEMP-TABLE ttTranslate NO-UNDO RCODE-INFORMATION FIELD dLanguageObj AS DECIMAL /* language object or 0 for login language */ FIELD cLanguageName AS CHARACTER FORMAT "X(20)":U LABEL "Language":U /* language name if known */ FIELD cObjectName AS CHARACTER FORMAT "X(40)":U LABEL "Object Name":U /* object name or blank for all */ FIELD lGlobal AS LOGICAL FORMAT "YES/NO":U LABEL "Global":U /* yes = global translation, no = specific object (if not blank) */ FIELD cWidgetType AS CHARACTER FORMAT "X(20)":U LABEL "Widget Type":U /* widget type, e.g. text, button, etc. */ FIELD cWidgetName AS CHARACTER FORMAT "X(40)":U LABEL "Widget Name":U /* widget name or if type is text, text to translate */ FIELD hWidgetHandle AS HANDLE /* handle of widget if known / required */ FIELD iWidgetEntry AS INTEGER FORMAT "9":U LABEL "Element":U /* widget entry, used for radio-sets, etc. */ FIELD lDelete AS LOGICAL FORMAT "YES/NO":U LABEL "Delete":U /* yes = global translation, no = specific object (if not blank) */ FIELD cTranslatedLabel AS CHARACTER FORMAT "X(30)":U LABEL "Translated Label":U /* translated label */ FIELD cOriginalLabel AS CHARACTER FORMAT "X(30)":U LABEL "Original Label":U /* original untranslated label */ FIELD cTranslatedTooltip AS CHARACTER FORMAT "X(40)":U LABEL "Translated Tooltip":U /* translated tooltip */ FIELD cOriginalTooltip AS CHARACTER FORMAT "X(40)":U LABEL "Original Tooltip":U /* original untranslated tooltip */ INDEX key1 AS UNIQUE PRIMARY dLanguageObj cObjectName cWidgetType cWidgetName hWidgetHandle iWidgetEntry INDEX key2 cLanguageName cObjectName cWidgetType cWidgetName iWidgetEntry INDEX key3 cObjectName cWidgetType cWidgetName iWidgetEntry INDEX key4 cWidgetName iWidgetEntry cObjectName cWidgetType . &GLOBAL-DEFINE ttTranslate &ENDIF

These fields should be familiar to you if you have seen the parameter list for getTranslation.

To use the Translation temp-table, first define it in the custom super procedure and then populate it:

Include the definition in the Definitions section of browsercustom.p, as shown:

{af/app/aftttranslate.i}

Populate the table in createBrowsePopupMenu to pass it in to multiTranslation. Define a variable with the text strings you need, and a counter variable to walk through them, as shown:

DEFINE VARIABLE cStrings AS CHARACTER NO-UNDO INIT "Move Columns,Sort Columns,Save Browser Settings,Reset Browser Settings,Exit". DEFINE VARIABLE iString AS INTEGER NO-UNDO.

Populate the temp-table with records for each of the strings needing translation, as shown:

DO iString = 1 TO NUM-ENTRIES(cStrings): CREATE ttTranslate. ASSIGN ttTranslate.dLanguageObj = 0 /* Use the login language */ ttTranslate.cObjectName = "" ttTranslate.lGlobal = NO ttTranslate.cWidgetType = "TEXT" ttTranslate.cWidgetName = ENTRY(iString, cStrings). END.

Pass this to the API call, as shown:

RUN multiTranslation IN gshTranslationManager (INPUT NO, /* Not for all languages */ INPUT-OUTPUT TABLE ttTranslate).

The same temp-table is returned with the cTranslatedLabel field filled with the translation. If the current language is the original language or if there is no translation for an item, then nothing is returned in the cTranslatedLabel field. Therefore you must check for this and use the original text string in that case, as shown:

/* If the current language is the original language or one for which there are no translations, then cTranslatedLabel is not set, so fall back on the original text. */ FOR EACH ttTranslate: IF ttTranslate.cTranslatedLabel = "" THEN ttTranslate.cTranslatedLabel = cWidgetName. END.

Retrieve the appropriate temp-table record for each of the menu items and use the translation for the label. Note that they will not (likely) come back in the order in which you created them because there’s no sequence assigned (as in the example above), as shown:

FIND ttTranslate WHERE ttTranslate.cWidgetName = "Move Columns". CREATE MENU-ITEM hColsMovableItem ASSIGN PARENT = hPopupMenu LABEL = ttTranslate.cTranslatedLabel /* "&Move Columns" */ NAME = "ColsMovable" TOGGLE-BOX = TRUE CHECKED = FALSE.

After you are done using the temp-table, empty it, as shown:

EMPTY TEMP-TABLE ttTranslate.

Save and compile the modifications to browsercustom.p, delete the current running instance of the super procedure in the Procedures ProTool, and return your test window. Now you see the translated strings, because you are logged in as a French user, as shown:

The Localization Manager itself uses translatePhrase and the other API calls here to translate titles, labels, and substitution arguments in messages. If you define text translations for these types of strings in your application, they will be translated for you in all the standard places where the framework handles translations. You can use the same calls as you did here to translate other text that the framework does not take care of for you.